home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_cvs.idb / usr / freeware / info / cvs.info-4.z / cvs.info-4
Text File  |  2002-01-08  |  51KB  |  1,263 lines
  1. This is cvs.info, produced by makeinfo version 4.0 from cvs.texinfo.
  2.  
  3. START-INFO-DIR-ENTRY
  4. * CVS: (cvs).          Concurrent Versions System
  5. END-INFO-DIR-ENTRY
  6.  
  7.    Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994
  8. Free Software Foundation, Inc.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided also
  16. that the entire resulting derived work is distributed under the terms
  17. of a permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions, except that this permission notice may be stated in a
  22. translation approved by the Free Software Foundation.
  23.  
  24. 
  25. File: cvs.info,  Node: Moving directories,  Prev: Moving files,  Up: Adding and removing
  26.  
  27. Moving and renaming directories
  28. ===============================
  29.  
  30.    The normal way to rename or move a directory is to rename or move
  31. each file within it as described in *Note Outside::.  Then check out
  32. with the `-P' option, as described in *Note Removing directories::.
  33.  
  34.    If you really want to hack the repository to rename or delete a
  35. directory in the repository, you can do it like this:
  36.  
  37.   1. Inform everyone who has a checked out copy of the directory that
  38.      the directory will be renamed.  They should commit all their
  39.      changes, and remove their working copies, before you take the
  40.      steps below.
  41.  
  42.   2. Rename the directory inside the repository.
  43.  
  44.           $ cd $CVSROOT/PARENT-DIR
  45.           $ mv OLD-DIR NEW-DIR
  46.  
  47.   3. Fix the CVS administrative files, if necessary (for instance if
  48.      you renamed an entire module).
  49.  
  50.   4. Tell everyone that they can check out again and continue working.
  51.  
  52.  
  53.    If someone had a working copy the CVS commands will cease to work
  54. for him, until he removes the directory that disappeared inside the
  55. repository.
  56.  
  57.    It is almost always better to move the files in the directory
  58. instead of moving the directory.  If you move the directory you are
  59. unlikely to be able to retrieve old releases correctly, since they
  60. probably depend on the name of the directories.
  61.  
  62. 
  63. File: cvs.info,  Node: History browsing,  Next: Binary files,  Prev: Adding and removing,  Up: Top
  64.  
  65. History browsing
  66. ****************
  67.  
  68.    Once you have used CVS to store a version control history--what
  69. files have changed when, how, and by whom, there are a variety of
  70. mechanisms for looking through the history.
  71.  
  72. * Menu:
  73.  
  74. * log messages::                Log messages
  75. * history database::            The history database
  76. * user-defined logging::        User-defined logging
  77. * annotate::                    What revision modified each line of a file?
  78.  
  79. 
  80. File: cvs.info,  Node: log messages,  Next: history database,  Up: History browsing
  81.  
  82. Log messages
  83. ============
  84.  
  85.    Whenever you commit a file you specify a log message.
  86.  
  87.    To look through the log messages which have been specified for every
  88. revision which has been committed, use the `cvs log' command (*note
  89. log::).
  90.  
  91. 
  92. File: cvs.info,  Node: history database,  Next: user-defined logging,  Prev: log messages,  Up: History browsing
  93.  
  94. The history database
  95. ====================
  96.  
  97.    You can use the history file (*note history file::) to log various
  98. CVS actions.  To retrieve the information from the history file, use
  99. the `cvs history' command (*note history::).
  100.  
  101.    Note: you can control what is logged to this file by using the
  102. `LogHistory' keyword in the `CVSROOT/config' file (*note config::).
  103.  
  104. 
  105. File: cvs.info,  Node: user-defined logging,  Next: annotate,  Prev: history database,  Up: History browsing
  106.  
  107. User-defined logging
  108. ====================
  109.  
  110.    You can customize CVS to log various kinds of actions, in whatever
  111. manner you choose.  These mechanisms operate by executing a script at
  112. various times.  The script might append a message to a file listing the
  113. information and the programmer who created it, or send mail to a group
  114. of developers, or, perhaps, post a message to a particular newsgroup.
  115. To log commits, use the `loginfo' file (*note loginfo::).  To log
  116. commits, checkouts, exports, and tags, respectively, you can also use
  117. the `-i', `-o', `-e', and `-t' options in the modules file.  For a more
  118. flexible way of giving notifications to various users, which requires
  119. less in the way of keeping centralized scripts up to date, use the `cvs
  120. watch add' command (*note Getting Notified::); this command is useful
  121. even if you are not using `cvs watch on'.
  122.  
  123.    The `taginfo' file defines programs to execute when someone executes
  124. a `tag' or `rtag' command.  The `taginfo' file has the standard form
  125. for administrative files (*note Administrative files::), where each
  126. line is a regular expression followed by a command to execute.  The
  127. arguments passed to the command are, in order, the TAGNAME, OPERATION
  128. (`add' for `tag', `mov' for `tag -F', and `del' for `tag -d'),
  129. REPOSITORY, and any remaining are pairs of FILENAME REVISION.  A
  130. non-zero exit of the filter program will cause the tag to be aborted.
  131.  
  132.    Here is an example of using taginfo to log tag and rtag commands.
  133. In the taginfo file put:
  134.  
  135.      ALL /usr/local/cvsroot/CVSROOT/loggit
  136.  
  137.    Where `/usr/local/cvsroot/CVSROOT/loggit' contains the following
  138. script:
  139.  
  140.      #!/bin/sh
  141.      echo "$@" >>/home/kingdon/cvsroot/CVSROOT/taglog
  142.  
  143. 
  144. File: cvs.info,  Node: annotate,  Prev: user-defined logging,  Up: History browsing
  145.  
  146. Annotate command
  147. ================
  148.  
  149.  - Command: cvs annotate [`-flR'] [`-r rev'|`-D date'] files ...
  150.      For each file in FILES, print the head revision of the trunk,
  151.      together with information on the last modification for each line.
  152.      For example:
  153.  
  154.           $ cvs annotate ssfile
  155.           Annotations for ssfile
  156.           ***************
  157.           1.1          (mary     27-Mar-96): ssfile line 1
  158.           1.2          (joe      28-Mar-96): ssfile line 2
  159.  
  160.      The file `ssfile' currently contains two lines.  The `ssfile line
  161.      1' line was checked in by `mary' on March 27.  Then, on March 28,
  162.      `joe' added a line `ssfile line 2', without modifying the `ssfile
  163.      line 1' line.  This report doesn't tell you anything about lines
  164.      which have been deleted or replaced; you need to use `cvs diff'
  165.      for that (*note diff::).
  166.  
  167.  
  168.    The options to `cvs annotate' are listed in *Note Invoking CVS::,
  169. and can be used to select the files and revisions to annotate.  The
  170. options are described in more detail in *Note Common options::.
  171.  
  172. 
  173. File: cvs.info,  Node: Binary files,  Next: Multiple developers,  Prev: History browsing,  Up: Top
  174.  
  175. Handling binary files
  176. *********************
  177.  
  178.    The most common use for CVS is to store text files.  With text
  179. files, CVS can merge revisions, display the differences between
  180. revisions in a human-visible fashion, and other such operations.
  181. However, if you are willing to give up a few of these abilities, CVS
  182. can store binary files.  For example, one might store a web site in CVS
  183. including both text files and binary images.
  184.  
  185. * Menu:
  186.  
  187. * Binary why::     More details on issues with binary files
  188. * Binary howto::   How to store them
  189.  
  190. 
  191. File: cvs.info,  Node: Binary why,  Next: Binary howto,  Up: Binary files
  192.  
  193. The issues with binary files
  194. ============================
  195.  
  196.    While the need to manage binary files may seem obvious if the files
  197. that you customarily work with are binary, putting them into version
  198. control does present some additional issues.
  199.  
  200.    One basic function of version control is to show the differences
  201. between two revisions.  For example, if someone else checked in a new
  202. version of a file, you may wish to look at what they changed and
  203. determine whether their changes are good.  For text files, CVS provides
  204. this functionality via the `cvs diff' command.  For binary files, it
  205. may be possible to extract the two revisions and then compare them with
  206. a tool external to CVS (for example, word processing software often has
  207. such a feature).  If there is no such tool, one must track changes via
  208. other mechanisms, such as urging people to write good log messages, and
  209. hoping that the changes they actually made were the changes that they
  210. intended to make.
  211.  
  212.    Another ability of a version control system is the ability to merge
  213. two revisions.  For CVS this happens in two contexts.  The first is
  214. when users make changes in separate working directories (*note Multiple
  215. developers::).  The second is when one merges explicitly with the
  216. `update -j' command (*note Branching and merging::).
  217.  
  218.    In the case of text files, CVS can merge changes made independently,
  219. and signal a conflict if the changes conflict.  With binary files, the
  220. best that CVS can do is present the two different copies of the file,
  221. and leave it to the user to resolve the conflict.  The user may choose
  222. one copy or the other, or may run an external merge tool which knows
  223. about that particular file format, if one exists.  Note that having the
  224. user merge relies primarily on the user to not accidentally omit some
  225. changes, and thus is potentially error prone.
  226.  
  227.    If this process is thought to be undesirable, the best choice may be
  228. to avoid merging.  To avoid the merges that result from separate
  229. working directories, see the discussion of reserved checkouts (file
  230. locking) in *Note Multiple developers::.  To avoid the merges resulting
  231. from branches, restrict use of branches.
  232.  
  233. 
  234. File: cvs.info,  Node: Binary howto,  Prev: Binary why,  Up: Binary files
  235.  
  236. How to store binary files
  237. =========================
  238.  
  239.    There are two issues with using CVS to store binary files.  The
  240. first is that CVS by default converts line endings between the
  241. canonical form in which they are stored in the repository (linefeed
  242. only), and the form appropriate to the operating system in use on the
  243. client (for example, carriage return followed by line feed for Windows
  244. NT).
  245.  
  246.    The second is that a binary file might happen to contain data which
  247. looks like a keyword (*note Keyword substitution::), so keyword
  248. expansion must be turned off.
  249.  
  250.    The `-kb' option available with some CVS commands insures that
  251. neither line ending conversion nor keyword expansion will be done.
  252.  
  253.    Here is an example of how you can create a new file using the `-kb'
  254. flag:
  255.  
  256.      $ echo '$Id$' > kotest
  257.      $ cvs add -kb -m"A test file" kotest
  258.      $ cvs ci -m"First checkin; contains a keyword" kotest
  259.  
  260.    If a file accidentally gets added without `-kb', one can use the
  261. `cvs admin' command to recover.  For example:
  262.  
  263.      $ echo '$Id$' > kotest
  264.      $ cvs add -m"A test file" kotest
  265.      $ cvs ci -m"First checkin; contains a keyword" kotest
  266.      $ cvs admin -kb kotest
  267.      $ cvs update -A kotest
  268.      # For non-unix systems:
  269.      # Copy in a good copy of the file from outside CVS
  270.      $ cvs commit -m "make it binary" kotest
  271.  
  272.    When you check in the file `kotest' the file is not preserved as a
  273. binary file, because you did not check it in as a binary file.  The `cvs
  274. admin -kb' command sets the default keyword substitution method for
  275. this file, but it does not alter the working copy of the file that you
  276. have.  If you need to cope with line endings (that is, you are using
  277. CVS on a non-unix system), then you need to check in a new copy of the
  278. file, as shown by the `cvs commit' command above.  On unix, the `cvs
  279. update -A' command suffices.
  280.  
  281.    However, in using `cvs admin -k' to change the keyword expansion, be
  282. aware that the keyword expansion mode is not version controlled.  This
  283. means that, for example, that if you have a text file in old releases,
  284. and a binary file with the same name in new releases, CVS provides no
  285. way to check out the file in text or binary mode depending on what
  286. version you are checking out.  There is no good workaround for this
  287. problem.
  288.  
  289.    You can also set a default for whether `cvs add' and `cvs import'
  290. treat a file as binary based on its name; for example you could say
  291. that files who names end in `.exe' are binary.  *Note Wrappers::.
  292. There is currently no way to have CVS detect whether a file is binary
  293. based on its contents.  The main difficulty with designing such a
  294. feature is that it is not clear how to distinguish between binary and
  295. non-binary files, and the rules to apply would vary considerably with
  296. the operating system.
  297.  
  298. 
  299. File: cvs.info,  Node: Multiple developers,  Next: Revision management,  Prev: Binary files,  Up: Top
  300.  
  301. Multiple developers
  302. *******************
  303.  
  304.    When more than one person works on a software project things often
  305. get complicated.  Often, two people try to edit the same file
  306. simultaneously.  One solution, known as "file locking" or "reserved
  307. checkouts", is to allow only one person to edit each file at a time.
  308. This is the only solution with some version control systems, including
  309. RCS and SCCS.  Currently the usual way to get reserved checkouts with
  310. CVS is the `cvs admin -l' command (*note admin options::).  This is not
  311. as nicely integrated into CVS as the watch features, described below,
  312. but it seems that most people with a need for reserved checkouts find
  313. it adequate.  It also may be possible to use the watches features
  314. described below, together with suitable procedures (not enforced by
  315. software), to avoid having two people edit at the same time.
  316.  
  317.    The default model with CVS is known as "unreserved checkouts".  In
  318. this model, developers can edit their own "working copy" of a file
  319. simultaneously.  The first person that commits his changes has no
  320. automatic way of knowing that another has started to edit it.  Others
  321. will get an error message when they try to commit the file.  They must
  322. then use CVS commands to bring their working copy up to date with the
  323. repository revision.  This process is almost automatic.
  324.  
  325.    CVS also supports mechanisms which facilitate various kinds of
  326. communication, without actually enforcing rules like reserved checkouts
  327. do.
  328.  
  329.    The rest of this chapter describes how these various models work,
  330. and some of the issues involved in choosing between them.
  331.  
  332. * Menu:
  333.  
  334. * File status::                 A file can be in several states
  335. * Updating a file::             Bringing a file up-to-date
  336. * Conflicts example::           An informative example
  337. * Informing others::            To cooperate you must inform
  338. * Concurrency::                 Simultaneous repository access
  339. * Watches::                     Mechanisms to track who is editing files
  340. * Choosing a model::            Reserved or unreserved checkouts?
  341.  
  342. 
  343. File: cvs.info,  Node: File status,  Next: Updating a file,  Up: Multiple developers
  344.  
  345. File status
  346. ===========
  347.  
  348.    Based on what operations you have performed on a checked out file,
  349. and what operations others have performed to that file in the
  350. repository, one can classify a file in a number of states.  The states,
  351. as reported by the `status' command, are:
  352.  
  353. Up-to-date
  354.      The file is identical with the latest revision in the repository
  355.      for the branch in use.
  356.  
  357. Locally Modified
  358.      You have edited the file, and not yet committed your changes.
  359.  
  360. Locally Added
  361.      You have added the file with `add', and not yet committed your
  362.      changes.
  363.  
  364. Locally Removed
  365.      You have removed the file with `remove', and not yet committed
  366.      your changes.
  367.  
  368. Needs Checkout
  369.      Someone else has committed a newer revision to the repository.
  370.      The name is slightly misleading; you will ordinarily use `update'
  371.      rather than `checkout' to get that newer revision.
  372.  
  373. Needs Patch
  374.      Like Needs Checkout, but the CVS server will send a patch rather
  375.      than the entire file.  Sending a patch or sending an entire file
  376.      accomplishes the same thing.
  377.  
  378. Needs Merge
  379.      Someone else has committed a newer revision to the repository, and
  380.      you have also made modifications to the file.
  381.  
  382. File had conflicts on merge
  383.      This is like Locally Modified, except that a previous `update'
  384.      command gave a conflict.  If you have not already done so, you
  385.      need to resolve the conflict as described in *Note Conflicts
  386.      example::.
  387.  
  388. Unknown
  389.      CVS doesn't know anything about this file.  For example, you have
  390.      created a new file and have not run `add'.
  391.  
  392.    To help clarify the file status, `status' also reports the `Working
  393. revision' which is the revision that the file in the working directory
  394. derives from, and the `Repository revision' which is the latest
  395. revision in the repository for the branch in use.
  396.  
  397.    The options to `status' are listed in *Note Invoking CVS::.  For
  398. information on its `Sticky tag' and `Sticky date' output, see *Note
  399. Sticky tags::.  For information on its `Sticky options' output, see the
  400. `-k' option in *Note update options::.
  401.  
  402.    You can think of the `status' and `update' commands as somewhat
  403. complementary.  You use `update' to bring your files up to date, and you
  404. can use `status' to give you some idea of what an `update' would do (of
  405. course, the state of the repository might change before you actually run
  406. `update').  In fact, if you want a command to display file status in a
  407. more brief format than is displayed by the `status' command, you can
  408. invoke
  409.  
  410.      $ cvs -n -q update
  411.  
  412.    The `-n' option means to not actually do the update, but merely to
  413. display statuses; the `-q' option avoids printing the name of each
  414. directory.  For more information on the `update' command, and these
  415. options, see *Note Invoking CVS::.
  416.  
  417. 
  418. File: cvs.info,  Node: Updating a file,  Next: Conflicts example,  Prev: File status,  Up: Multiple developers
  419.  
  420. Bringing a file up to date
  421. ==========================
  422.  
  423.    When you want to update or merge a file, use the `update' command.
  424. For files that are not up to date this is roughly equivalent to a
  425. `checkout' command: the newest revision of the file is extracted from
  426. the repository and put in your working directory.
  427.  
  428.    Your modifications to a file are never lost when you use `update'.
  429. If no newer revision exists, running `update' has no effect.  If you
  430. have edited the file, and a newer revision is available, CVS will merge
  431. all changes into your working copy.
  432.  
  433.    For instance, imagine that you checked out revision 1.4 and started
  434. editing it.  In the meantime someone else committed revision 1.5, and
  435. shortly after that revision 1.6.  If you run `update' on the file now,
  436. CVS will incorporate all changes between revision 1.4 and 1.6 into your
  437. file.
  438.  
  439.    If any of the changes between 1.4 and 1.6 were made too close to any
  440. of the changes you have made, an "overlap" occurs.  In such cases a
  441. warning is printed, and the resulting file includes both versions of
  442. the lines that overlap, delimited by special markers.  *Note update::,
  443. for a complete description of the `update' command.
  444.  
  445. 
  446. File: cvs.info,  Node: Conflicts example,  Next: Informing others,  Prev: Updating a file,  Up: Multiple developers
  447.  
  448. Conflicts example
  449. =================
  450.  
  451.    Suppose revision 1.4 of `driver.c' contains this:
  452.  
  453.      #include <stdio.h>
  454.      
  455.      void main()
  456.      {
  457.          parse();
  458.          if (nerr == 0)
  459.              gencode();
  460.          else
  461.              fprintf(stderr, "No code generated.\n");
  462.          exit(nerr == 0 ? 0 : 1);
  463.      }
  464.  
  465. Revision 1.6 of `driver.c' contains this:
  466.  
  467.      #include <stdio.h>
  468.      
  469.      int main(int argc,
  470.               char **argv)
  471.      {
  472.          parse();
  473.          if (argc != 1)
  474.          {
  475.              fprintf(stderr, "tc: No args expected.\n");
  476.              exit(1);
  477.          }
  478.          if (nerr == 0)
  479.              gencode();
  480.          else
  481.              fprintf(stderr, "No code generated.\n");
  482.          exit(!!nerr);
  483.      }
  484.  
  485. Your working copy of `driver.c', based on revision 1.4, contains this
  486. before you run `cvs update':
  487.  
  488.      #include <stdlib.h>
  489.      #include <stdio.h>
  490.      
  491.      void main()
  492.      {
  493.          init_scanner();
  494.          parse();
  495.          if (nerr == 0)
  496.              gencode();
  497.          else
  498.              fprintf(stderr, "No code generated.\n");
  499.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  500.      }
  501.  
  502. You run `cvs update':
  503.  
  504.      $ cvs update driver.c
  505.      RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  506.      retrieving revision 1.4
  507.      retrieving revision 1.6
  508.      Merging differences between 1.4 and 1.6 into driver.c
  509.      rcsmerge warning: overlaps during merge
  510.      cvs update: conflicts found in driver.c
  511.      C driver.c
  512.  
  513. CVS tells you that there were some conflicts.  Your original working
  514. file is saved unmodified in `.#driver.c.1.4'.  The new version of
  515. `driver.c' contains this:
  516.  
  517.      #include <stdlib.h>
  518.      #include <stdio.h>
  519.      
  520.      int main(int argc,
  521.               char **argv)
  522.      {
  523.          init_scanner();
  524.          parse();
  525.          if (argc != 1)
  526.          {
  527.              fprintf(stderr, "tc: No args expected.\n");
  528.              exit(1);
  529.          }
  530.          if (nerr == 0)
  531.              gencode();
  532.          else
  533.              fprintf(stderr, "No code generated.\n");
  534.      <<<<<<< driver.c
  535.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  536.      =======
  537.          exit(!!nerr);
  538.      >>>>>>> 1.6
  539.      }
  540.  
  541. Note how all non-overlapping modifications are incorporated in your
  542. working copy, and that the overlapping section is clearly marked with
  543. `<<<<<<<', `=======' and `>>>>>>>'.
  544.  
  545.    You resolve the conflict by editing the file, removing the markers
  546. and the erroneous line.  Suppose you end up with this file:
  547.      #include <stdlib.h>
  548.      #include <stdio.h>
  549.      
  550.      int main(int argc,
  551.               char **argv)
  552.      {
  553.          init_scanner();
  554.          parse();
  555.          if (argc != 1)
  556.          {
  557.              fprintf(stderr, "tc: No args expected.\n");
  558.              exit(1);
  559.          }
  560.          if (nerr == 0)
  561.              gencode();
  562.          else
  563.              fprintf(stderr, "No code generated.\n");
  564.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  565.      }
  566.  
  567. You can now go ahead and commit this as revision 1.7.
  568.  
  569.      $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
  570.      Checking in driver.c;
  571.      /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
  572.      new revision: 1.7; previous revision: 1.6
  573.      done
  574.  
  575.    For your protection, CVS will refuse to check in a file if a
  576. conflict occurred and you have not resolved the conflict.  Currently to
  577. resolve a conflict, you must change the timestamp on the file.  In
  578. previous versions of CVS, you also needed to insure that the file
  579. contains no conflict markers.  Because your file may legitimately
  580. contain conflict markers (that is, occurrences of `>>>>>>> ' at the
  581. start of a line that don't mark a conflict), the current version of CVS
  582. will print a warning and proceed to check in the file.
  583.  
  584.    If you use release 1.04 or later of pcl-cvs (a GNU Emacs front-end
  585. for CVS) you can use an Emacs package called emerge to help you resolve
  586. conflicts.  See the documentation for pcl-cvs.
  587.  
  588. 
  589. File: cvs.info,  Node: Informing others,  Next: Concurrency,  Prev: Conflicts example,  Up: Multiple developers
  590.  
  591. Informing others about commits
  592. ==============================
  593.  
  594.    It is often useful to inform others when you commit a new revision
  595. of a file.  The `-i' option of the `modules' file, or the `loginfo'
  596. file, can be used to automate this process.  *Note modules::.  *Note
  597. loginfo::.  You can use these features of CVS to, for instance,
  598. instruct CVS to mail a message to all developers, or post a message to
  599. a local newsgroup.
  600.  
  601. 
  602. File: cvs.info,  Node: Concurrency,  Next: Watches,  Prev: Informing others,  Up: Multiple developers
  603.  
  604. Several developers simultaneously attempting to run CVS
  605. =======================================================
  606.  
  607.    If several developers try to run CVS at the same time, one may get
  608. the following message:
  609.  
  610.      [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
  611.  
  612.    CVS will try again every 30 seconds, and either continue with the
  613. operation or print the message again, if it still needs to wait.  If a
  614. lock seems to stick around for an undue amount of time, find the person
  615. holding the lock and ask them about the cvs command they are running.
  616. If they aren't running a cvs command, look in the repository directory
  617. mentioned in the message and remove files which they own whose names
  618. start with `#cvs.rfl', `#cvs.wfl', or `#cvs.lock'.
  619.  
  620.    Note that these locks are to protect CVS's internal data structures
  621. and have no relationship to the word "lock" in the sense used by
  622. RCS--which refers to reserved checkouts (*note Multiple developers::).
  623.  
  624.    Any number of people can be reading from a given repository at a
  625. time; only when someone is writing do the locks prevent other people
  626. from reading or writing.
  627.  
  628.    One might hope for the following property
  629.  
  630.      If someone commits some changes in one cvs command,
  631.      then an update by someone else will either get all the
  632.      changes, or none of them.
  633.  
  634.    but CVS does _not_ have this property.  For example, given the files
  635.  
  636.      a/one.c
  637.      a/two.c
  638.      b/three.c
  639.      b/four.c
  640.  
  641.    if someone runs
  642.  
  643.      cvs ci a/two.c b/three.c
  644.  
  645.    and someone else runs `cvs update' at the same time, the person
  646. running `update' might get only the change to `b/three.c' and not the
  647. change to `a/two.c'.
  648.  
  649. 
  650. File: cvs.info,  Node: Watches,  Next: Choosing a model,  Prev: Concurrency,  Up: Multiple developers
  651.  
  652. Mechanisms to track who is editing files
  653. ========================================
  654.  
  655.    For many groups, use of CVS in its default mode is perfectly
  656. satisfactory.  Users may sometimes go to check in a modification only
  657. to find that another modification has intervened, but they deal with it
  658. and proceed with their check in.  Other groups prefer to be able to
  659. know who is editing what files, so that if two people try to edit the
  660. same file they can choose to talk about who is doing what when rather
  661. than be surprised at check in time.  The features in this section allow
  662. such coordination, while retaining the ability of two developers to
  663. edit the same file at the same time.
  664.  
  665.    For maximum benefit developers should use `cvs edit' (not `chmod')
  666. to make files read-write to edit them, and `cvs release' (not `rm') to
  667. discard a working directory which is no longer in use, but CVS is not
  668. able to enforce this behavior.
  669.  
  670. * Menu:
  671.  
  672. * Setting a watch::             Telling CVS to watch certain files
  673. * Getting Notified::            Telling CVS to notify you
  674. * Editing files::               How to edit a file which is being watched
  675. * Watch information::           Information about who is watching and editing
  676. * Watches Compatibility::       Watches interact poorly with CVS 1.6 or earlier
  677.  
  678. 
  679. File: cvs.info,  Node: Setting a watch,  Next: Getting Notified,  Up: Watches
  680.  
  681. Telling CVS to watch certain files
  682. ----------------------------------
  683.  
  684.    To enable the watch features, you first specify that certain files
  685. are to be watched.
  686.  
  687.  - Command: cvs watch on [`-lR'] files ...
  688.      Specify that developers should run `cvs edit' before editing
  689.      FILES.  CVS will create working copies of FILES read-only, to
  690.      remind developers to run the `cvs edit' command before working on
  691.      them.
  692.  
  693.      If FILES includes the name of a directory, CVS arranges to watch
  694.      all files added to the corresponding repository directory, and
  695.      sets a default for files added in the future; this allows the user
  696.      to set notification policies on a per-directory basis.  The
  697.      contents of the directory are processed recursively, unless the
  698.      `-l' option is given.  The `-R' option can be used to force
  699.      recursion if the `-l' option is set in `~/.cvsrc' (*note
  700.      ~/.cvsrc::).
  701.  
  702.      If FILES is omitted, it defaults to the current directory.
  703.  
  704.  
  705.  - Command: cvs watch off [`-lR'] files ...
  706.      Do not create FILES read-only on checkout; thus, developers will
  707.      not be reminded to use `cvs edit' and `cvs unedit'.
  708.  
  709.      The FILES and options are processed as for `cvs watch on'.
  710.  
  711.  
  712. 
  713. File: cvs.info,  Node: Getting Notified,  Next: Editing files,  Prev: Setting a watch,  Up: Watches
  714.  
  715. Telling CVS to notify you
  716. -------------------------
  717.  
  718.    You can tell CVS that you want to receive notifications about
  719. various actions taken on a file.  You can do this without using `cvs
  720. watch on' for the file, but generally you will want to use `cvs watch
  721. on', so that developers use the `cvs edit' command.
  722.  
  723.  - Command: cvs watch add [`-a' action] [`-lR'] files ...
  724.      Add the current user to the list of people to receive notification
  725.      of work done on FILES.
  726.  
  727.      The `-a' option specifies what kinds of events CVS should notify
  728.      the user about.  ACTION is one of the following:
  729.  
  730.     `edit'
  731.           Another user has applied the `cvs edit' command (described
  732.           below) to a file.
  733.  
  734.     `unedit'
  735.           Another user has applied the `cvs unedit' command (described
  736.           below) or the `cvs release' command to a file, or has deleted
  737.           the file and allowed `cvs update' to recreate it.
  738.  
  739.     `commit'
  740.           Another user has committed changes to a file.
  741.  
  742.     `all'
  743.           All of the above.
  744.  
  745.     `none'
  746.           None of the above.  (This is useful with `cvs edit',
  747.           described below.)
  748.  
  749.      The `-a' option may appear more than once, or not at all.  If
  750.      omitted, the action defaults to `all'.
  751.  
  752.      The FILES and options are processed as for the `cvs watch'
  753.      commands.
  754.  
  755.  
  756.  - Command: cvs watch remove [`-a' action] [`-lR'] files ...
  757.      Remove a notification request established using `cvs watch add';
  758.      the arguments are the same.  If the `-a' option is present, only
  759.      watches for the specified actions are removed.
  760.  
  761.  
  762.    When the conditions exist for notification, CVS calls the `notify'
  763. administrative file.  Edit `notify' as one edits the other
  764. administrative files (*note Intro administrative files::).  This file
  765. follows the usual conventions for administrative files (*note
  766. syntax::), where each line is a regular expression followed by a
  767. command to execute.  The command should contain a single occurrence of
  768. `%s' which will be replaced by the user to notify; the rest of the
  769. information regarding the notification will be supplied to the command
  770. on standard input.  The standard thing to put in the `notify' file is
  771. the single line:
  772.  
  773.      ALL mail %s -s "CVS notification"
  774.  
  775.    This causes users to be notified by electronic mail.
  776.  
  777.    Note that if you set this up in the straightforward way, users
  778. receive notifications on the server machine.  One could of course write
  779. a `notify' script which directed notifications elsewhere, but to make
  780. this easy, CVS allows you to associate a notification address for each
  781. user.  To do so create a file `users' in `CVSROOT' with a line for each
  782. user in the format USER:VALUE.  Then instead of passing the name of the
  783. user to be notified to `notify', CVS will pass the VALUE (normally an
  784. email address on some other machine).
  785.  
  786.    CVS does not notify you for your own changes.  Currently this check
  787. is done based on whether the user name of the person taking the action
  788. which triggers notification matches the user name of the person getting
  789. notification.  In fact, in general, the watches features only track one
  790. edit by each user.  It probably would be more useful if watches tracked
  791. each working directory separately, so this behavior might be worth
  792. changing.
  793.  
  794. 
  795. File: cvs.info,  Node: Editing files,  Next: Watch information,  Prev: Getting Notified,  Up: Watches
  796.  
  797. How to edit a file which is being watched
  798. -----------------------------------------
  799.  
  800.    Since a file which is being watched is checked out read-only, you
  801. cannot simply edit it.  To make it read-write, and inform others that
  802. you are planning to edit it, use the `cvs edit' command.  Some systems
  803. call this a "checkout", but CVS uses that term for obtaining a copy of
  804. the sources (*note Getting the source::), an operation which those
  805. systems call a "get" or a "fetch".
  806.  
  807.  - Command: cvs edit [options] files ...
  808.      Prepare to edit the working files FILES.  CVS makes the FILES
  809.      read-write, and notifies users who have requested `edit'
  810.      notification for any of FILES.
  811.  
  812.      The `cvs edit' command accepts the same OPTIONS as the `cvs watch
  813.      add' command, and establishes a temporary watch for the user on
  814.      FILES; CVS will remove the watch when FILES are `unedit'ed or
  815.      `commit'ted.  If the user does not wish to receive notifications,
  816.      she should specify `-a none'.
  817.  
  818.      The FILES and options are processed as for the `cvs watch'
  819.      commands.
  820.  
  821.  
  822.    Normally when you are done with a set of changes, you use the `cvs
  823. commit' command, which checks in your changes and returns the watched
  824. files to their usual read-only state.  But if you instead decide to
  825. abandon your changes, or not to make any changes, you can use the `cvs
  826. unedit' command.
  827.  
  828.  - Command: cvs unedit [`-lR'] files ...
  829.      Abandon work on the working files FILES, and revert them to the
  830.      repository versions on which they are based.  CVS makes those
  831.      FILES read-only for which users have requested notification using
  832.      `cvs watch on'.  CVS notifies users who have requested `unedit'
  833.      notification for any of FILES.
  834.  
  835.      The FILES and options are processed as for the `cvs watch'
  836.      commands.
  837.  
  838.      If watches are not in use, the `unedit' command probably does not
  839.      work, and the way to revert to the repository version is to remove
  840.      the file and then use `cvs update' to get a new copy.  The meaning
  841.      is not precisely the same; removing and updating may also bring in
  842.      some changes which have been made in the repository since the last
  843.      time you updated.
  844.  
  845.    When using client/server CVS, you can use the `cvs edit' and `cvs
  846. unedit' commands even if CVS is unable to successfully communicate with
  847. the server; the notifications will be sent upon the next successful CVS
  848. command.
  849.  
  850. 
  851. File: cvs.info,  Node: Watch information,  Next: Watches Compatibility,  Prev: Editing files,  Up: Watches
  852.  
  853. Information about who is watching and editing
  854. ---------------------------------------------
  855.  
  856.  - Command: cvs watchers [`-lR'] files ...
  857.      List the users currently watching changes to FILES.  The report
  858.      includes the files being watched, and the mail address of each
  859.      watcher.
  860.  
  861.      The FILES and options are processed as for the `cvs watch'
  862.      commands.
  863.  
  864.  
  865.  - Command: cvs editors [`-lR'] files ...
  866.      List the users currently working on FILES.  The report includes
  867.      the mail address of each user, the time when the user began
  868.      working with the file, and the host and path of the working
  869.      directory containing the file.
  870.  
  871.      The FILES and options are processed as for the `cvs watch'
  872.      commands.
  873.  
  874.  
  875. 
  876. File: cvs.info,  Node: Watches Compatibility,  Prev: Watch information,  Up: Watches
  877.  
  878. Using watches with old versions of CVS
  879. --------------------------------------
  880.  
  881.    If you use the watch features on a repository, it creates `CVS'
  882. directories in the repository and stores the information about watches
  883. in that directory.  If you attempt to use CVS 1.6 or earlier with the
  884. repository, you get an error message such as the following (all on one
  885. line):
  886.  
  887.      cvs update: cannot open CVS/Entries for reading:
  888.      No such file or directory
  889.  
  890.    and your operation will likely be aborted.  To use the watch
  891. features, you must upgrade all copies of CVS which use that repository
  892. in local or server mode.  If you cannot upgrade, use the `watch off' and
  893. `watch remove' commands to remove all watches, and that will restore
  894. the repository to a state which CVS 1.6 can cope with.
  895.  
  896. 
  897. File: cvs.info,  Node: Choosing a model,  Prev: Watches,  Up: Multiple developers
  898.  
  899. Choosing between reserved or unreserved checkouts
  900. =================================================
  901.  
  902.    Reserved and unreserved checkouts each have pros and cons.  Let it
  903. be said that a lot of this is a matter of opinion or what works given
  904. different groups' working styles, but here is a brief description of
  905. some of the issues.  There are many ways to organize a team of
  906. developers.  CVS does not try to enforce a certain organization.  It is
  907. a tool that can be used in several ways.
  908.  
  909.    Reserved checkouts can be very counter-productive.  If two persons
  910. want to edit different parts of a file, there may be no reason to
  911. prevent either of them from doing so.  Also, it is common for someone
  912. to take out a lock on a file, because they are planning to edit it, but
  913. then forget to release the lock.
  914.  
  915.    People, especially people who are familiar with reserved checkouts,
  916. often wonder how often conflicts occur if unreserved checkouts are
  917. used, and how difficult they are to resolve.  The experience with many
  918. groups is that they occur rarely and usually are relatively
  919. straightforward to resolve.
  920.  
  921.    The rarity of serious conflicts may be surprising, until one realizes
  922. that they occur only when two developers disagree on the proper design
  923. for a given section of code; such a disagreement suggests that the team
  924. has not been communicating properly in the first place.  In order to
  925. collaborate under _any_ source management regimen, developers must
  926. agree on the general design of the system; given this agreement,
  927. overlapping changes are usually straightforward to merge.
  928.  
  929.    In some cases unreserved checkouts are clearly inappropriate.  If no
  930. merge tool exists for the kind of file you are managing (for example
  931. word processor files or files edited by Computer Aided Design
  932. programs), and it is not desirable to change to a program which uses a
  933. mergeable data format, then resolving conflicts is going to be
  934. unpleasant enough that you generally will be better off to simply avoid
  935. the conflicts instead, by using reserved checkouts.
  936.  
  937.    The watches features described above in *Note Watches:: can be
  938. considered to be an intermediate model between reserved checkouts and
  939. unreserved checkouts.  When you go to edit a file, it is possible to
  940. find out who else is editing it.  And rather than having the system
  941. simply forbid both people editing the file, it can tell you what the
  942. situation is and let you figure out whether it is a problem in that
  943. particular case or not.  Therefore, for some groups it can be
  944. considered the best of both the reserved checkout and unreserved
  945. checkout worlds.
  946.  
  947. 
  948. File: cvs.info,  Node: Revision management,  Next: Keyword substitution,  Prev: Multiple developers,  Up: Top
  949.  
  950. Revision management
  951. *******************
  952.  
  953.    If you have read this far, you probably have a pretty good grasp on
  954. what CVS can do for you.  This chapter talks a little about things that
  955. you still have to decide.
  956.  
  957.    If you are doing development on your own using CVS you could
  958. probably skip this chapter.  The questions this chapter takes up become
  959. more important when more than one person is working in a repository.
  960.  
  961. * Menu:
  962.  
  963. * When to commit::              Some discussion on the subject
  964.  
  965. 
  966. File: cvs.info,  Node: When to commit,  Up: Revision management
  967.  
  968. When to commit?
  969. ===============
  970.  
  971.    Your group should decide which policy to use regarding commits.
  972. Several policies are possible, and as your experience with CVS grows
  973. you will probably find out what works for you.
  974.  
  975.    If you commit files too quickly you might commit files that do not
  976. even compile.  If your partner updates his working sources to include
  977. your buggy file, he will be unable to compile the code.  On the other
  978. hand, other persons will not be able to benefit from the improvements
  979. you make to the code if you commit very seldom, and conflicts will
  980. probably be more common.
  981.  
  982.    It is common to only commit files after making sure that they can be
  983. compiled.  Some sites require that the files pass a test suite.
  984. Policies like this can be enforced using the commitinfo file (*note
  985. commitinfo::), but you should think twice before you enforce such a
  986. convention.  By making the development environment too controlled it
  987. might become too regimented and thus counter-productive to the real
  988. goal, which is to get software written.
  989.  
  990. 
  991. File: cvs.info,  Node: Keyword substitution,  Next: Tracking sources,  Prev: Revision management,  Up: Top
  992.  
  993. Keyword substitution
  994. ********************
  995.  
  996.    As long as you edit source files inside a working directory you can
  997. always find out the state of your files via `cvs status' and `cvs log'.
  998. But as soon as you export the files from your development environment
  999. it becomes harder to identify which revisions they are.
  1000.  
  1001.    CVS can use a mechanism known as "keyword substitution" (or "keyword
  1002. expansion") to help identifying the files.  Embedded strings of the form
  1003. `$KEYWORD$' and `$KEYWORD:...$' in a file are replaced with strings of
  1004. the form `$KEYWORD:VALUE$' whenever you obtain a new revision of the
  1005. file.
  1006.  
  1007. * Menu:
  1008.  
  1009. * Keyword list::                Keywords
  1010. * Using keywords::              Using keywords
  1011. * Avoiding substitution::       Avoiding substitution
  1012. * Substitution modes::          Substitution modes
  1013. * Log keyword::                 Problems with the $Log$ keyword.
  1014.  
  1015. 
  1016. File: cvs.info,  Node: Keyword list,  Next: Using keywords,  Up: Keyword substitution
  1017.  
  1018. Keyword List
  1019. ============
  1020.  
  1021.    This is a list of the keywords:
  1022.  
  1023. `$Author$'
  1024.      The login name of the user who checked in the revision.
  1025.  
  1026. `$Date$'
  1027.      The date and time (UTC) the revision was checked in.
  1028.  
  1029. `$Header$'
  1030.      A standard header containing the full pathname of the RCS file,
  1031.      the revision number, the date (UTC), the author, the state, and
  1032.      the locker (if locked).  Files will normally never be locked when
  1033.      you use CVS.
  1034.  
  1035. `$Id$'
  1036.      Same as `$Header$', except that the RCS filename is without a path.
  1037.  
  1038. `$Name$'
  1039.      Tag name used to check out this file.  The keyword is expanded
  1040.      only if one checks out with an explicit tag name.  For example,
  1041.      when running the command `cvs co -r first', the keyword expands to
  1042.      `Name: first'.
  1043.  
  1044. `$Locker$'
  1045.      The login name of the user who locked the revision (empty if not
  1046.      locked, which is the normal case unless `cvs admin -l' is in use).
  1047.  
  1048. `$Log$'
  1049.      The log message supplied during commit, preceded by a header
  1050.      containing the RCS filename, the revision number, the author, and
  1051.      the date (UTC).  Existing log messages are _not_ replaced.
  1052.      Instead, the new log message is inserted after `$Log:...$'.  Each
  1053.      new line is prefixed with the same string which precedes the
  1054.      `$Log' keyword.  For example, if the file contains
  1055.  
  1056.             /* Here is what people have been up to:
  1057.              *
  1058.              * $Log: frob.c,v $
  1059.              * Revision 1.1  1997/01/03 14:23:51  joe
  1060.              * Add the superfrobnicate option
  1061.              *
  1062.              */
  1063.  
  1064.      then additional lines which are added when expanding the `$Log'
  1065.      keyword will be preceded by `   * '.  Unlike previous versions of
  1066.      CVS and RCS, the "comment leader" from the RCS file is not used.
  1067.      The `$Log' keyword is useful for accumulating a complete change
  1068.      log in a source file, but for several reasons it can be
  1069.      problematic.  *Note Log keyword::.
  1070.  
  1071. `$RCSfile$'
  1072.      The name of the RCS file without a path.
  1073.  
  1074. `$Revision$'
  1075.      The revision number assigned to the revision.
  1076.  
  1077. `$Source$'
  1078.      The full pathname of the RCS file.
  1079.  
  1080. `$State$'
  1081.      The state assigned to the revision.  States can be assigned with
  1082.      `cvs admin -s'--see *Note admin options::.
  1083.  
  1084. 
  1085. File: cvs.info,  Node: Using keywords,  Next: Avoiding substitution,  Prev: Keyword list,  Up: Keyword substitution
  1086.  
  1087. Using keywords
  1088. ==============
  1089.  
  1090.    To include a keyword string you simply include the relevant text
  1091. string, such as `$Id$', inside the file, and commit the file.  CVS will
  1092. automatically expand the string as part of the commit operation.
  1093.  
  1094.    It is common to embed the `$Id$' string in the source files so that
  1095. it gets passed through to generated files.  For example, if you are
  1096. managing computer program source code, you might include a variable
  1097. which is initialized to contain that string.  Or some C compilers may
  1098. provide a `#pragma ident' directive.  Or a document management system
  1099. might provide a way to pass a string through to generated files.
  1100.  
  1101.    The `ident' command (which is part of the RCS package) can be used
  1102. to extract keywords and their values from a file.  This can be handy
  1103. for text files, but it is even more useful for extracting keywords from
  1104. binary files.
  1105.  
  1106.      $ ident samp.c
  1107.      samp.c:
  1108.           $Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
  1109.      $ gcc samp.c
  1110.      $ ident a.out
  1111.      a.out:
  1112.           $Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
  1113.  
  1114.    SCCS is another popular revision control system.  It has a command,
  1115. `what', which is very similar to `ident' and used for the same purpose.
  1116. Many sites without RCS have SCCS.  Since `what' looks for the
  1117. character sequence `@(#)' it is easy to include keywords that are
  1118. detected by either command.  Simply prefix the keyword with the magic
  1119. SCCS phrase, like this:
  1120.  
  1121.      static char *id="@(#) $Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
  1122.  
  1123. 
  1124. File: cvs.info,  Node: Avoiding substitution,  Next: Substitution modes,  Prev: Using keywords,  Up: Keyword substitution
  1125.  
  1126. Avoiding substitution
  1127. =====================
  1128.  
  1129.    Keyword substitution has its disadvantages.  Sometimes you might
  1130. want the literal text string `$Author$' to appear inside a file without
  1131. CVS interpreting it as a keyword and expanding it into something like
  1132. `$Author: ceder $'.
  1133.  
  1134.    There is unfortunately no way to selectively turn off keyword
  1135. substitution.  You can use `-ko' (*note Substitution modes::) to turn
  1136. off keyword substitution entirely.
  1137.  
  1138.    In many cases you can avoid using keywords in the source, even
  1139. though they appear in the final product.  For example, the source for
  1140. this manual contains `$@asis{}Author$' whenever the text `$Author$'
  1141. should appear.  In `nroff' and `troff' you can embed the null-character
  1142. `\&' inside the keyword for a similar effect.
  1143.  
  1144. 
  1145. File: cvs.info,  Node: Substitution modes,  Next: Log keyword,  Prev: Avoiding substitution,  Up: Keyword substitution
  1146.  
  1147. Substitution modes
  1148. ==================
  1149.  
  1150.    Each file has a stored default substitution mode, and each working
  1151. directory copy of a file also has a substitution mode.  The former is
  1152. set by the `-k' option to `cvs add' and `cvs admin'; the latter is set
  1153. by the `-k' or `-A' options to `cvs checkout' or `cvs update'.  `cvs
  1154. diff' also has a `-k' option.  For some examples, see *Note Binary
  1155. files::, and *Note Merging and keywords::.
  1156.  
  1157.    The modes available are:
  1158.  
  1159. `-kkv'
  1160.      Generate keyword strings using the default form, e.g.  `$Revision:
  1161.      5.7 $' for the `Revision' keyword.
  1162.  
  1163. `-kkvl'
  1164.      Like `-kkv', except that a locker's name is always inserted if the
  1165.      given revision is currently locked.  The locker's name is only
  1166.      relevant if `cvs admin -l' is in use.
  1167.  
  1168. `-kk'
  1169.      Generate only keyword names in keyword strings; omit their values.
  1170.      For example, for the `Revision' keyword, generate the string
  1171.      `$Revision$' instead of `$Revision: 5.7 $'.  This option is useful
  1172.      to ignore differences due to keyword substitution when comparing
  1173.      different revisions of a file (*note Merging and keywords::).
  1174.  
  1175. `-ko'
  1176.      Generate the old keyword string, present in the working file just
  1177.      before it was checked in.  For example, for the `Revision'
  1178.      keyword, generate the string `$Revision: 1.1 $' instead of
  1179.      `$Revision: 5.7 $' if that is how the string appeared when the
  1180.      file was checked in.
  1181.  
  1182. `-kb'
  1183.      Like `-ko', but also inhibit conversion of line endings between
  1184.      the canonical form in which they are stored in the repository
  1185.      (linefeed only), and the form appropriate to the operating system
  1186.      in use on the client.  For systems, like unix, which use linefeed
  1187.      only to terminate lines, this is the same as `-ko'.  For more
  1188.      information on binary files, see *Note Binary files::.
  1189.  
  1190. `-kv'
  1191.      Generate only keyword values for keyword strings.  For example,
  1192.      for the `Revision' keyword, generate the string `5.7' instead of
  1193.      `$Revision: 5.7 $'.  This can help generate files in programming
  1194.      languages where it is hard to strip keyword delimiters like
  1195.      `$Revision: $' from a string.  However, further keyword
  1196.      substitution cannot be performed once the keyword names are
  1197.      removed, so this option should be used with care.
  1198.  
  1199.      One often would like to use `-kv' with `cvs export'--*note
  1200.      export::.  But be aware that doesn't handle an export containing
  1201.      binary files correctly.
  1202.  
  1203. 
  1204. File: cvs.info,  Node: Log keyword,  Prev: Substitution modes,  Up: Keyword substitution
  1205.  
  1206. Problems with the $Log$ keyword.
  1207. ================================
  1208.  
  1209.    The `$Log$' keyword is somewhat controversial.  As long as you are
  1210. working on your development system the information is easily accessible
  1211. even if you do not use the `$Log$' keyword--just do a `cvs log'.  Once
  1212. you export the file the history information might be useless anyhow.
  1213.  
  1214.    A more serious concern is that CVS is not good at handling `$Log$'
  1215. entries when a branch is merged onto the main trunk.  Conflicts often
  1216. result from the merging operation.
  1217.  
  1218.    People also tend to "fix" the log entries in the file (correcting
  1219. spelling mistakes and maybe even factual errors).  If that is done the
  1220. information from `cvs log' will not be consistent with the information
  1221. inside the file.  This may or may not be a problem in real life.
  1222.  
  1223.    It has been suggested that the `$Log$' keyword should be inserted
  1224. _last_ in the file, and not in the files header, if it is to be used at
  1225. all.  That way the long list of change messages will not interfere with
  1226. everyday source file browsing.
  1227.  
  1228. 
  1229. File: cvs.info,  Node: Tracking sources,  Next: Builds,  Prev: Keyword substitution,  Up: Top
  1230.  
  1231. Tracking third-party sources
  1232. ****************************
  1233.  
  1234.    If you modify a program to better fit your site, you probably want
  1235. to include your modifications when the next release of the program
  1236. arrives.  CVS can help you with this task.
  1237.  
  1238.    In the terminology used in CVS, the supplier of the program is
  1239. called a "vendor".  The unmodified distribution from the vendor is
  1240. checked in on its own branch, the "vendor branch".  CVS reserves branch
  1241. 1.1.1 for this use.
  1242.  
  1243.    When you modify the source and commit it, your revision will end up
  1244. on the main trunk.  When a new release is made by the vendor, you
  1245. commit it on the vendor branch and copy the modifications onto the main
  1246. trunk.
  1247.  
  1248.    Use the `import' command to create and update the vendor branch.
  1249. When you import a new file, the vendor branch is made the `head'
  1250. revision, so anyone that checks out a copy of the file gets that
  1251. revision.  When a local modification is committed it is placed on the
  1252. main trunk, and made the `head' revision.
  1253.  
  1254. * Menu:
  1255.  
  1256. * First import::                Importing for the first time
  1257. * Update imports::              Updating with the import command
  1258. * Reverting local changes::     Reverting to the latest vendor release
  1259. * Binary files in imports::     Binary files require special handling
  1260. * Keywords in imports::         Keyword substitution might be undesirable
  1261. * Multiple vendor branches::    What if you get sources from several places?
  1262.  
  1263.